:::tip Experimental
This documents unreleased main — not a released, committed API. See
the API stability policy and use Stable
instead.
:::
Robotiq::Gripper Class
The Robotiq gripper Class.
Construction opens the link, reads the gripper — failing like a dead serial link when it does not answer — and starts the exchange cycle; destruction stops it. Control is instant: setCommand() and getStatus() access an internal process image and never touch the bus. The control image seeds from the gripper's own status echoes, so connecting never disturbs a gripper that is already running.
Concurrency model: accessors are thread-safe; the intended use is one control thread writing commands while a background exchange thread reads/writes the wire. Reads are whole snapshots and writes are whole commands — no per-field accessors, deliberately: every transmitted frame is a command the application composed, and two fields never come from different exchange cycles. The blocking calls are waitForExchange() and waitForExchangeCount().
Included Headers
Members
| Public Constructors | |
| Gripper (const ConnectionConfig &config, std::shared_ptr< Logger > logger=nullptr) | |
|
The common-case constructor: create a gripper object and start communication over the built-in serial transport and the default platform. More... | |
| Gripper (std::unique_ptr< Serial > serial, uint8_t slaveAddress, std::chrono::microseconds exchangePeriod, std::shared_ptr< Platform > platform, std::shared_ptr< Logger > logger=nullptr) | |
|
A general-purpose constructor for cases where the common-case constructor does not apply. Start communication over a caller-supplied transport and platform. More... | |
| Gripper (const Gripper &)=delete | |
| Public Destructor | |
| ~Gripper () | |
|
Stops the exchange cycle and closes the link. More... | |
| Public Operators | |
| Gripper & | operator= (const Gripper &)=delete |
| Public Member Functions | |
| void | setCommand (const GripperCommand &command) |
|
Send a new command block on the next exchange cycle. More... | |
| GripperCommand | getCommand () const |
| GripperStatus | getStatus () const |
| StampedExchange | getMostRecentStampedExchange () const |
| std::optional< StampedExchange > | waitForExchange (std::chrono::milliseconds timeout=std::chrono::seconds(30)) const |
|
Block until an exchange completes or a timeout occurs. More... | |
| std::optional< StampedExchange > | waitForExchangeCount (uint64_t desiredExchangeCount, std::chrono::milliseconds timeout=std::chrono::seconds(30)) const |
|
Block until the exchange count reaches a value or a timeout occurs. More... | |
| ConnectionState | connectionState () const |
| Platform & | platform () const noexcept |
Public Constructors
Gripper()
| explicit |
The common-case constructor: create a gripper object and start communication over the built-in serial transport and the default platform.
- Parameters
-
config see ConnectionConfig.
logger Log sink; pass null to use the default stderr logger.
- Exceptions
-
<a href="/docs/drivers/Adaptive grippers/Libraries/C++/next/API/classes/robotiq/serialioexception">SerialIOException</a> when the port cannot be opened/configured.
<a href="/docs/drivers/Adaptive grippers/Libraries/C++/next/API/classes/robotiq/driverexception">DriverException</a> when no gripper answers the initial read, or when config.connectionFrequency is invalid.
Gripper()
|
A general-purpose constructor for cases where the common-case constructor does not apply. Start communication over a caller-supplied transport and platform.
- Parameters
-
serial The transport to exchange over; must not be null.
slaveAddress The gripper's Modbus slave address.
exchangePeriod Period of the background exchange cycle.
platform Runtime services (thread, lock, sleep) for the exchange to run on; must not be null.
logger Log sink; pass null to use the build's default logger.
- Exceptions
-
<a href="/docs/drivers/Adaptive grippers/Libraries/C++/next/API/classes/robotiq/serialioexception">SerialIOException</a> when the port cannot be opened/configured.
<a href="/docs/drivers/Adaptive grippers/Libraries/C++/next/API/classes/robotiq/driverexception">DriverException</a> when no gripper answers the initial read, when exchangePeriod is invalid, or when platform is null.
Gripper()
| delete |
Public Destructor
~Gripper()
|
Stops the exchange cycle and closes the link.
Public Member Functions
connectionState()
|
- Returns
The current state of the background exchange; see ConnectionState.
getCommand()
|
- Returns
The last command block passed to setCommand() — or the gripper's own echoed state, before the first call.
getMostRecentStampedExchange()
|
- Returns
The most recent stamped exchange.
getStatus()
|
- Returns
A snapshot of the gripper's last received status block.
platform()
| noexcept |
Return the runtime Platform used by this gripper.
For most applications the function below should never be used. In some cases, such as embedded applications, it is needed for platform-specific versions of free functions such as waitFor and waitUntil.
setCommand()
|
Send a new command block on the next exchange cycle.
- Parameters
-
command The whole command block to transmit; see GripperCommand.
waitForExchange()
|
Block until an exchange completes or a timeout occurs.
This form is typically used to wait for an event to occur, such as a desired status. Exchanges that complete between two calls are not returned; a loop that must see every exchange uses waitForExchangeCount().
- Parameters
-
timeout How long to wait; 30 s by default.
- Returns
The first exchange completed after the call — the latest, if several did; empty when timeout elapsed first.
- Example
-
bool waitForMotionEnd(Robotiq::Gripper& gripper){// Each wake-up sees the newest exchange; the ones in between are not needed here.while(std::optional<Robotiq::StampedExchange> exchange = gripper.waitForExchange(1s)){if(exchange->status.gripperStatus.objectDetection() != Robotiq::ObjectDetection::Moving){return true;}}return false; // no exchange completed within the timeout}
waitForExchangeCount()
|
Block until the exchange count reaches a value or a timeout occurs.
This form is typically used for control loop synchronization: a loop asks for one past the exchange it last acted on, so it sees every exchange exactly once, and one that fell behind gets the newest at once instead of waiting a cycle.
- Parameters
-
desiredExchangeCount Wait until at least this many exchanges have completed since the connection to the gripper.
timeout How long to wait; 30 s by default.
- Returns
The latest exchange once the count is reached; empty when timeout elapsed first.
- Example
-
const std::optional<StampedExchange> exchange = _gripper.waitForExchangeCount(written + 1, kCycleTimeout);if(!exchange){continue; // a stalled link: nothing landed, so nothing to log}const uint64_t count = exchange->metadata.exchangeCount;if(count != written + 1){// The count reached is the newest, not the next: the loop fell behind._skipped += count - written - 1;_logger.log(Logger::Level::Warn,"fell behind: exchanges " + std::to_string(written + 1) + " to " + std::to_string(count - 1)+ " not logged");}writeRow(_csv, start, *exchange);written = count;
The documentation for this class was generated from the following file:
- gripper.hpp
Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.9.8.